home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / seyon / MultiList.h < prev    next >
C/C++ Source or Header  |  1995-05-03  |  12KB  |  307 lines
  1. /****************************************************************************
  2.  
  3.     MultiList.h
  4.  
  5.     This file is the public header file for the MultiList widget, an
  6.     extension to the Athena List widget.
  7.  
  8.     This code is loosely based on the Athena List source which
  9.     is why the MIT copyright notice appears below.
  10.  
  11.     The code was changed substantially in V3.4 to change the
  12.     action/callback interface which was unnecessarily ugly.  Code
  13.     using some features of the old interface may need to be changed.
  14.     Hope the changes don't make people's lives too miserable.
  15.  
  16.  ****************************************************************************/
  17.  
  18. /*
  19.  * Author:
  20.  *     Brian Totty
  21.  *     Department of Computer Science
  22.  *     University Of Illinois at Urbana-Champaign
  23.  *    1304 West Springfield Avenue
  24.  *     Urbana, IL 61801
  25.  * 
  26.  *     totty@cs.uiuc.edu
  27.  *     
  28.  */ 
  29.  
  30. /*
  31.  * Copyright 1989 Massachusetts Institute of Technology
  32.  *
  33.  * Permission to use, copy, modify, distribute, and sell this software and its
  34.  * documentation for any purpose is hereby granted without fee, provided that
  35.  * the above copyright notice appear in all copies and that both that
  36.  * copyright notice and this permission notice appear in supporting
  37.  * documentation, and that the name of M.I.T. not be used in advertising or
  38.  * publicity pertaining to distribution of the software without specific,
  39.  * written prior permission.  M.I.T. makes no representations about the
  40.  * suitability of this software for any purpose.  It is provided "as is"
  41.  * without express or implied warranty.
  42.  *
  43.  * M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  44.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T.
  45.  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  46.  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  47.  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 
  48.  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  49.  *
  50.  * Original Athena Author:  Chris D. Peterson, MIT X Consortium
  51.  */
  52.  
  53. #ifndef _MULTILIST_H_
  54. #define _MULTILIST_H_
  55.  
  56. #include <X11/Xaw/Simple.h>
  57.  
  58. /*---------------------------------------------------------------------------*
  59.  
  60.       R E S O U R C E    D E S C R I P T I O N S    A N D    N O T E S
  61.  
  62.  *---------------------------------------------------------------------------*/
  63.  
  64. /*
  65.  
  66.  Name             Class        RepType        Default Value
  67.  ----             -----        -------        -------------
  68.  background         Background        Pixel        XtDefaultBackground
  69.  border             BorderColor    Pixel        XtDefaultForeground
  70.  borderWidth         BorderWidth    Dimension    1
  71.  callback            Callback           XtCallbackList  NULL                *1
  72.  columnWidth         Width              Dimension       0                   *9
  73.  columnSpacing       Spacing            Dimension       8
  74.  cursor             Cursor        Cursor        left_ptr
  75.  defaultColumns      Columns            int             1                   *2
  76.  destroyCallback     Callback        Pointer        NULL 
  77.  font             Font        XFontStruct*    XtDefaultFont
  78.  forceColumns        Columns            Boolean         False               *2
  79.  foreground         Foreground        Pixel        XtDefaultForeground
  80.  height             Height        Dimension    0                   *3
  81.  highlightBackground HBackground    Pixel        XtDefaultForeground *4
  82.  highlightForeground HForeground    Pixel        XtDefaultBackground *4
  83.  insensitiveBorder   Insensitive    Pixmap        Gray
  84.  list                List               String *        NULL                *5
  85.  longest             Longest            int             0                   *6
  86.  mappedWhenManaged   MappedWhenManaged    Boolean        True
  87.  maxSelectable       Value              int             1                   *7
  88.  numberStrings       NumberStrings      int             0                   *5
  89.  pasteBuffer         Boolean            Boolean         False
  90.  rowHeight           Height             Dimension       0                   *9
  91.  rowSpacing          Spacing            Dimension       2
  92.  sensitive         Sensitive        Boolean        True
  93.  sensitiveArray      List               Boolean *       NULL                *8
  94.  shadeSurplus         Boolean        Boolean        True            *10
  95.  verticalList        Boolean            Boolean         False
  96.  width             Width        Dimension    0
  97.  x             Position        Position    0
  98.  y             Position        Position    0
  99.  
  100.  *1 -  The callback functions are called whenever a highlight or unhighlight
  101.        takes place.  More precisely, a callback occurs whenever the Notify()
  102.        action is triggered.  By default, this occurs when the mouse button is
  103.        lifted after a selection or deselection occurred.  The callback returns
  104.        an XfwfMultiListReturnStruct data structure which contains numerous
  105.        fields describing the selection state.  The most important fields
  106.        indicate the total number of items selected, and a list of those items.
  107.  
  108.  *2 -  The defaultColumns resource is used in two cases.  If forceColumns
  109.        is true, the widget will set the number of columns to the value of
  110.        default columns.  If the widget width is unconstrained by the parent
  111.        widgets, the defaultColumns is also used to determine the number of
  112.        columns and the resulting width.  Otherwise, the number of columns
  113.        will be calcultaed based on the current width and will be changed to
  114.        an appropriate value.
  115.  
  116.  *3 -  If the width or height is set to zero (0), which is the default case,
  117.        then the widget will calculate the size of that dimension to be just
  118.        large enough to hold the contents of the widget.
  119.  
  120.  *4 -  The highlightForeground and highlightBackground colors specify the
  121.        colors used to highlight the text (foreground) and the surrounding
  122.        background space of a list item when it is selected (highlighted).
  123.        The default is the reverse of the default foreground and background
  124.        colors.
  125.  
  126.  *5 -  The list resource is an array of strings (char * array) which tell
  127.        the names of each item of the list.  The number of elements of this
  128.        array are indicated by the resource numberStrings.  If numberStrings
  129.        is set to 0 (the default), then the MultiList widget will count the
  130.        number of strings in the list.  This requires that the list be
  131.        NULL terminated.  If list is NULL, then the widget treats it as an
  132.        empty list.  Once the list is set the list resource is set to NULL,
  133.        so you won't be able to read back the list after it has been set.  The
  134.        widgets copies the strings internally, so the user can free the list
  135.        storage after setting it.
  136.  
  137.  *6 -  This resource represent the longest string in pixels.  If this
  138.        resource is zero (0), which is the default and probably the value
  139.        most people should use, the longest string length is calculated
  140.        and the resource is updated.
  141.  
  142.  *7 -  The maxSelectable resource indicates the maximum number of items
  143.        which can be selected at any one time.  In the original Athena
  144.        widget, you could have at most one item selected at a time.  In
  145.        this widget, you can choose how many will be selected at a time.
  146.  
  147.  *8 -  Each item in the MultiList can be made insensitive, so it is printed in
  148.        gray shading and can not be highlighted.  This can be done by
  149.        setting the sensitivity list, which is an array of Booleans which
  150.        indicate whether or not the corresponding item is sensitive (can be
  151.        selected).  If sensitivity list is NULL, all items are sensitive.  The
  152.        widget copies the sensitivity information, so the user can delete the
  153.        sensitivity array storage after setting it.  The widget sets the
  154.        resource to NULL after it has been set, so the user cannot read the
  155.        old list back.
  156.  
  157.  *9 -  These values are intended for reading only.  They indicate the pixel
  158.        width/height of the column/row.
  159.  
  160.  *10 - If the list height is made larger than the sum of the list entry
  161.        heights, the surplus space is shaded in the background color if
  162.        shadeSurplus is False, or in a gray stipple pattern if shadeSurplus
  163.        is True.       
  164.  
  165. */
  166.  
  167. /*---------------------------------------------------------------------------*
  168.  
  169.                     S T R I N G    D E F I N I T I O N S
  170.  
  171.  *---------------------------------------------------------------------------*/
  172.  
  173. #ifndef XtCList
  174. #define XtCList            "List"
  175. #endif
  176.  
  177. #ifndef XtCSpacing
  178. #define XtCSpacing        "Spacing"
  179. #endif
  180.  
  181. #ifndef XtCColumns
  182. #define XtCColumns        "Columns"
  183. #endif
  184.  
  185. #ifndef XtCLongest
  186. #define XtCLongest        "Longest"
  187. #endif
  188.  
  189. #define XtCNumberStrings    "NumberStrings"
  190. #define    XtCHForeground        "HForeground"
  191. #define    XtCHBackground        "HBackground"
  192.  
  193. #ifndef XtNcursor
  194. #define XtNcursor        "cursor"
  195. #endif
  196.  
  197. #define    XtNhighlightForeground    "highlightForeground"
  198. #define    XtNhighlightBackground    "highlightBackground"
  199. #define XtNcolumnSpacing    "columnSpacing"
  200.  
  201.  
  202. #ifndef XtNrowSpacing
  203. #define XtNrowSpacing        "rowSpacing"
  204. #endif
  205.  
  206. #define XtNdefaultColumns    "defaultColumns"
  207.  
  208. #ifndef XtNforceColumns
  209. #define XtNforceColumns        "forceColumns"
  210. #endif
  211.  
  212. #ifndef XtNpasteBuffer
  213. #define XtNpasteBuffer        "pasteBuffer"
  214. #endif
  215.  
  216. #ifndef XtNverticalList
  217. #define XtNverticalList        "verticalList"
  218. #endif
  219.  
  220. #ifndef XtNlongest
  221. #define XtNlongest        "longest"
  222. #endif
  223.  
  224. #define XtNnumberStrings    "numberStrings"
  225.  
  226. #ifndef XtNlist
  227. #define XtNlist            "list"
  228. #endif
  229.  
  230. #define    XtNsensitiveArray    "sensitiveArray"
  231. #define    XtNmaxSelectable    "maxSelectable"
  232. #define    XtNshadeSurplus        "shadeSurplus"
  233.  
  234. #define    XtNrowHeight        "rowHeight"
  235. #define    XtNcolumnWidth        "columnWidth"
  236.  
  237.     /* Class Record Constants */
  238.  
  239. extern WidgetClass xfwfMultiListWidgetClass;
  240.  
  241. typedef struct _XfwfMultiListClassRec *XfwfMultiListWidgetClass;
  242. typedef struct _XfwfMultiListRec      *XfwfMultiListWidget;
  243.  
  244. /*---------------------------------------------------------------------------*
  245.  
  246.                      R E T U R N    S T R U C T U R E
  247.  
  248.  *---------------------------------------------------------------------------*/
  249.  
  250. #define    XfwfMultiListActionNothing        0
  251. #define    XfwfMultiListActionHighlight        1
  252. #define    XfwfMultiListActionUnhighlight        2
  253. #define    XfwfMultiListActionStatus        3
  254.  
  255. typedef struct _XfwfMultiListReturnStruct
  256. {
  257.     int num_selected;        /* Number Of Items Now Selected */
  258.     int *selected_items;        /* Indexes Of Selected Items */
  259.  
  260.     int action;            /* Last Action Performed */
  261.     int item;            /* Last Item Index Modified */
  262.     String string;            /* String Of Last Index Modified */
  263. } XfwfMultiListReturnStruct;
  264.  
  265. /*---------------------------------------------------------------------------*
  266.  
  267.                      U T I L I T Y    R O U T I N E S
  268.  
  269.  *---------------------------------------------------------------------------*/
  270.  
  271. #if (!NeedFunctionPrototypes)
  272.  
  273. extern Boolean        XfwfMultiListHighlightItem();
  274. extern void        XfwfMultiListHighlightAll();
  275. extern void        XfwfMultiListUnhighlightItem();
  276. extern void        XfwfMultiListUnhighlightAll();
  277. extern int        XfwfMultiListToggleItem();
  278. extern XfwfMultiListReturnStruct *
  279.             XfwfMultiListGetHighlighted();
  280. extern Boolean        XfwfMultiListIsHighlighted();
  281. extern Boolean        XfwfMultiListGetItemInfo();
  282. extern void        XfwfMultiListSetNewData();
  283.  
  284. #else
  285.  
  286. extern Boolean        XfwfMultiListHighlightItem(XfwfMultiListWidget mlw,
  287.                 int item_index);
  288. extern void        XfwfMultiListHighlightAll(XfwfMultiListWidget mlw);
  289. extern void        XfwfMultiListUnhighlightItem(XfwfMultiListWidget mlw,
  290.                 int item_index);
  291. extern void        XfwfMultiListUnhighlightAll(XfwfMultiListWidget mlw);
  292. extern int        XfwfMultiListToggleItem(XfwfMultiListWidget mlw,
  293.                 int item_index);
  294. extern XfwfMultiListReturnStruct *
  295.             XfwfMultiListGetHighlighted(XfwfMultiListWidget mlw);
  296. extern Boolean        XfwfMultiListIsHighlighted(XfwfMultiListWidget mlw,
  297.                 int item_index);
  298. extern Boolean        XfwfMultiListGetItemInfo(XfwfMultiListWidget mlw,
  299.                 int item_index, String *str_ptr,
  300.                 Boolean *h_ptr, Boolean *s_ptr);
  301. extern void        XfwfMultiListSetNewData(XfwfMultiListWidget mlw,
  302.                 String *list, int nitems, int longest,
  303.                 int resize, Boolean *sensitivity_array);
  304.  
  305. #endif
  306. #endif
  307.